home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1995 November / EnigmA AMIGA RUN 02 (1995)(G.R. Edizioni)(IT)[!][issue 1995-11][Skylink CD].iso / earcd / program / assembly / dass05sc.lha / readme.doc < prev   
Text File  |  1995-10-08  |  14KB  |  352 lines
  1. dass05sc - version 0.92  (08.10.1995)
  2. -some serious bugs removed
  3. -eol remark parsing order changed (look at the lines with '!' remarks)
  4. -echo command expanded ( " )
  5. dass05sc - version 0.92  (29.09.1995)
  6. -additional end-of-line remark command for controlfile operation
  7. -minor changes
  8. dass05sc - version 0.9   (27.08.1995)
  9. -first release
  10.  
  11. (c)1995 by Klaus Hegemann
  12.  
  13.  
  14.  
  15. INTRODUCTION:
  16.  
  17.    dass05sc allows you to monitor/disassemble binary data of at least
  18. the Motorola MC68HC05SC21 smart card microcontroller.
  19. Command line operation is supported as well as a 'batch' like control-
  20. file operation (recommended).
  21.  
  22.    FOR THE QUICKSTARTERS: have a look at the EXAMPLES at the end of
  23. this text.
  24.  
  25.    There are slight differences between the Amiga and the PC version of
  26. this program concerning the command line syntax. Have a look at
  27. 'DIFFERENCES'
  28.  
  29.  
  30. BACKGROUND:
  31.  
  32.    Well, it was hard enough to find a disassembler for the 68hc05 type
  33.    microprocessor until I was told that the 68hc05_SC_ makes use of a
  34.    modified coding of the instruction byte. :-|  And, as far as I searched
  35.    some of the 'motorola stuff'-filled ftp servers and the motorola bbs
  36.    itself in Germany there seemed to be no disassembler for this type of uP
  37.    publicly available. Thanks to Marc Wirth who responded to my complains
  38.    ;-) and supplied me with information about the smart card version of the
  39.    hc05. To cut it short: There was no disassembler, so I had to write one.
  40.    As a result, I added some more features and decided to make it public
  41.    available.
  42.  
  43.  
  44. USAGE:
  45.  
  46.    AmigaOS Template: BINFILE/A,CONTROLFILE=CF/K,START=S/K,END=E/K,
  47.    OFFSET=O/K,PLUSHEXDUMP=DM/S,HEXONLY=M/S
  48.  
  49.    general Information on template usage:
  50.    '/A': required argument; '/K': keyword, must be placed in front of the
  51.    argument; '/S': switch option; 'WORD1=W1':  WORD1 and W1 do have the
  52.    same meaning. Use as keyword or switch.
  53.  
  54.    BINFILE:         Filename of the binary to be disassembled.
  55.    CONTROLFILE=CF:  Option: 'batch'-like operation mode (see below). No
  56.                     further command line args needed, except the BINFILEname.
  57.    command line operation:
  58.    START=S:         Specify the start location within the binary for
  59.                     disassembly and hexdump
  60.    END=E:           end location for disassembly/hex dump. If not specified
  61.                     a default of 20 output lines is set.
  62.    OFFSET=O:        If your binary proviedes relocated code, you may specify
  63.                     a signed value to cause the output to appear at a correct
  64.                     location. E.g. your binary contains the smart card memory
  65.                     image $0000 - $1fff with activated 1st codepage and
  66.                     from $2000 - $3fff with activated second codepage:
  67.                     simply specify an offset of -$2000 when inspecting code
  68.                     of the second code page.
  69.    PLUSHEXDUMP=DM:  An additional hex dump is placed on the right side near
  70.                     the disassebled output. Useful e.g. to distinguish
  71.                     between wild code and ascii text...
  72.    HEXONLY=M:       Memory hex-dump option.
  73.  
  74.  
  75. EXAMPLES: CLI
  76.  
  77.    >dass05sc t:bin start=$1000
  78.    >dass05sc t:bin start $1000
  79.    >dass05sc t:bin s=$1000
  80.    >dass05sc t:bin s=4096
  81.    they all produce the same output:
  82.    ====================<begin>====================================
  83.    *** dass05sc V0.9 disassembler for 68hc05sc21 type binaries ***
  84.    (w)1995 by Klaus Hegemann. Freely distributable.
  85.    
  86.    read 16384 data bytes from file 'bin'
  87.    
  88.    1000: 00         rti                
  89.    
  90.    1001: 00         rti                
  91.    
  92.    1002: 00         rti                
  93.    
  94.    1003: 00         rti                
  95.    
  96.    1004: 00         rti                
  97.    
  98.    1005: 00         rti                
  99.    
  100.    1006: 00         rti                
  101.    
  102.    1007: 00         rti                
  103.    
  104.    1008: 00         rti                
  105.    
  106.    1009: 00         rti                
  107.    
  108.    100a: 00         rti                
  109.    
  110.    100b: 00         rti
  111.    ====================<end>======================================
  112.  
  113.    >dass05sc t:bin hexonly start=$1000 end=$1020
  114.    >dass05sc t:bin m start=$1000 end=$1020
  115.    >dass05sc t:bin m start=4096 end=4128
  116.    each one results in:
  117.    ====================<begin>====================================
  118.    [...]
  119.    read 16384 data bytes from file 't:bin'
  120.    
  121.    1000: 00 00 00 00 00 00 00 00   '........'
  122.    1008: 00 00 00 00 00 00 00 00   '........'
  123.    1010: 00 00 00 00 00 00 00 00   '........'
  124.    1018: 00 00 00 00 00 00 00 00   '........'
  125.    1020: 00
  126.    ====================<end>======================================
  127.  
  128.    >dass05sc t:bin plushexdump start=$07e9 end=$07fd offset=-$07e9
  129.    >dass05sc t:bin dm s=$07e9 e=$07fd o=-$07e9
  130.    each one results in:
  131.    ====================<begin>====================================
  132.    [...]
  133.    read 16384 data bytes from file 't:bin'
  134.  
  135.    0000: 2f         txa                0000:    2f 4d 1d 3d 3f 87 37   ' /M.=?.7'
  136.    0001: 4d 1d 3d   jsr   $1d3d        
  137.    0004: 3f 87      stx   $87          
  138.    0006: 37 95      sta   $95          0007: 95 3b 96 93 3a 3b 93 97   '.;..:;..'
  139.    0008: 3b 96      ldx   $96          
  140.    000a: 93 3a      bne   $0046        
  141.    000c: 3b 93      ldx   $93          
  142.    000e: 97 04      beq   $0014        000f: 04 16 06 96 32 3b         '....2;  '
  143.    0010: 16 06      cpx   #$06         
  144.    0012: 96 32      bls   $0046        
  145.    0014: 3b a6      ldx   $a6
  146.    ====================<end>======================================
  147.  
  148.  
  149.  
  150. EXAMPLES: CONTROLFILE:
  151.  
  152.    In controlfile operation there are some differences/additions:
  153.    The line:
  154.    e "***"
  155.      simply outputs the chars between the two (")s
  156. !  e 27
  157. !    drops the char code 27 (ESCape). useful, if you want to supply
  158. !    e.g. printer control strings. There is only one number after
  159. !    each 'e'-command allowed. However, you may append a string:
  160. !  e 12 "Hello next page !" 
  161. !    performs a form feed and prints the string on top of the next
  162. !    page.
  163. !    Normally, a (CR+) LF is performed after each 'e'-command that
  164. !    comes with a string. You may prevent this by using a '\' as the
  165. !    last character.
  166. !  e "Good morning \"
  167. !  e $30 "0\"
  168. !  e "7 !"
  169. !    these commands will cause the output string "Good morning 007!"
  170. !    (followed by (CR+) LF).
  171. !    You may use this feature, when supplying printer control commands
  172. !    where additional (CR+)LS's aren't needed.
  173.    d <start> <end> <offset>
  174.      will disassemble from <start> to <end> with an offset of <offset>
  175.      No keywords are allowed. <start> and <end> must be specified,
  176.      <offset> may not. You may use hexadecimal Numbers, introduced
  177.      by a '$'. If not, the line parser expects a decimal value.
  178.    d- <start> <end> <offset>
  179.      Suppresses additional blank lines after JMPs, BRAs, STOPs, WAITs,
  180.      etc.
  181.    m <start> <end> <offset>
  182.      Memory hex-dump
  183.    dm- <start> <end> <offset>
  184.      Disassembler dump with additional hex dump, no extra blank lines
  185.      after JMPs, BRAs, etc...
  186.    r <address> <offset> "hmm, doughnuts"
  187.      Adds an end-of-line remark to the disassembled or hex dumped line
  188.      at <address>. You have to supply the same values for <address>
  189.      and <offset> that you have used in the disassemble/hex dump
  190.      command. If you do no supply the offset value, '$0000' will be
  191.      taken as default.
  192.      For each disassemble or hex dump job the remark commands must
  193.      be sorted by their address values. 
  194. !    The eol-remark parser scanns the controlfile sequentially, so
  195. !    each remark line is read only once, i.e. it looks out for the
  196. !    first eol-remark command, then waits until this address occurs
  197. !    before the next eol-remark command will be processed.
  198.      This should not be too much restrictive at all, I think.
  199.      However, it makes the [kind of slow] processing a bit faster.)
  200.      
  201.      
  202.    controlfile 't:control' consists of (without the '>'):
  203.    ====================<begin>====================================
  204.    e "***************************************"
  205.    e "*  lots of zero's                     *"
  206.    e "***************************************"
  207.    m $052a $0543 -$0100
  208.    e "***************************************"
  209.    e "*  some machine code                  *"
  210.    e "***************************************"
  211.    d $0573 $057c
  212.    e "***************************************"
  213.    e "* and now with additional hex dump    *"
  214.    e "***************************************"
  215.    dm $0573 $057c -$73
  216.    e "%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%"
  217.    e "% in jump tables there is no need for %"
  218.    e "% empty lines after JMPs, BRAs,...    %"
  219.    e "%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%"
  220.    d- $0573 $057c -$73
  221.    e "%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%"
  222.    dm- $0573 $057c -$73
  223.    r  $057a -$0100 "hmm, invisible cola"
  224.    r  $0573 "woo-hooouu"
  225.    ====================<end>======================================
  226.    will be used by dass05sc if you supply the 'CONTROLFILE' keaword:
  227.    
  228.    >dass05sc t:bin controlfile=t:control
  229.    >dass05sc t:bin cf=t:control
  230.  
  231.    that will cause the following output:   
  232.    ====================<begin>====================================
  233.    *** dass05sc V0.9 disassembler for 68hc05sc21 type binaries ***
  234.    (w)1995 by Klaus Hegemann. Freely distributable.
  235.    
  236.    read 16384 data bytes from file 't:bin'
  237.    
  238.    ***************************************
  239.    *  lots of zero's                     *
  240.    ***************************************
  241.    042a:       00 00 00 00 00 00   '  ......'  hmm, invisible cola
  242.    0430: 00 00 00 00 00 00 00 00   '........'
  243.    0438: 00 00 00 00 00 00 00 00   '........'
  244.    0440: 00 00 00 00               '....    '
  245.    ***************************************
  246.    *  some machine code                  *
  247.    ***************************************
  248.    0573: 49 13 bf   jmp   $13bf       woo-hooouu 
  249.    
  250.    0576: 49 14 93   jmp   $1493
  251.    
  252.    0579: 49 14 cf   jmp   $14cf        
  253.    
  254.    057c: 49 14 ab   jmp   $14ab        
  255.    
  256.    ***************************************
  257.    * and now with additional hex dump    *
  258.    ***************************************
  259.    0500: 49 13 bf   jmp   $13bf        0500:          49 13 bf 49 14   '   I..I.'
  260.    
  261.    0503: 49 14 93   jmp   $1493        0505: 93 49 14 cf 49            '.I..I   '  wohooouu
  262.    
  263.    0506: 49 14 cf   jmp   $14cf        
  264.    
  265.    0509: 49 14 ab   jmp   $14ab        
  266.    
  267.    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  268.    % in jump tables there is no need for %
  269.    % empty lines after jmps, bras,...    %
  270.    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  271.    0500: 49 13 bf   jmp   $13bf        
  272.    0503: 49 14 93   jmp   $1493       
  273.    0506: 49 14 cf   jmp   $14cf        
  274.    0509: 49 14 ab   jmp   $14ab        
  275.    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  276.    0500: 49 13 bf   jmp   $13bf        0500:          49 13 bf 49 14   '   I..I.'
  277.    0503: 49 14 93   jmp   $1493        0505: 93 49 14 cf 49            '.I..I   '  wohooouu
  278.    0506: 49 14 cf   jmp   $14cf        
  279.    0509: 49 14 ab   jmp   $14ab        
  280.    
  281.    ====================<end>======================================
  282.    
  283.  
  284.    In controlfile operation you are supposed to prefer a file
  285.    in wich the information should be dumped.
  286.    To achieve that, simply use the output redirect option that
  287.    comes with your DOS: (Amiga and PC as well)
  288.  
  289.    >dass05sc t:bin controlfile=t:control >disassembled.txt
  290.    >dass05sc t:bin cf=t:control >disassembled.txt
  291.  
  292.  
  293. DIFFERENCES: (usage Amiga <-> PC)
  294.  
  295.      Only the command line hanling is concerned. On the Amiga, I prefered
  296.    using the command line parser that comes with AmigaOS, rather than
  297.    the ANSI parser supplied with the C-Compiler.
  298.      
  299.    On the PC the command line usage is almost the same:
  300.    * you  must supply the keywords in its short form.
  301.          (e.g. 'CF' insted of 'CONTROLFILE')
  302.    * you must supply a '=' after the keywords.
  303.    
  304.    
  305. BUGS:
  306.  
  307.      No error messages yet, it simply quits if something's wrong.
  308.    I suggest that you may provoke a crash, if the cli/controlfile syntax 
  309.    becomes too obscure...
  310.    All in all and as you can see it at the version number, this proggi
  311.    is still a kind of 'beta', quick & dirty... but right now there are
  312.    other things (i.e. the next exams) that I ought to worry about.
  313.  
  314.  
  315. DISCLAIMER/DISTRIBUTION:
  316.  
  317.      Both programs, the Amiga and the PC version of this program are
  318.    freely distributible, but they are not public domain.
  319.    The contents of this distribution are copyrigthed matrial, and may not
  320.    be altered without express permission of the author.
  321.      dass05sc may be distributed by any means, electronic or physical,
  322.    provided no charge, other than for small handling fees such as disk
  323.    medium charges, is made.  It may be distributed on commercial electronic
  324.    networking services, provided that no fee is made explicitly for it's
  325.    acquirement, though a general blanket downloading charge is permissable.
  326.    Inclusion on the Aminet and Fred Fish CDs is welcomed due to their long
  327.    standing support of the Amiga.
  328.      I am in no way responsible in any damage that may result in using this
  329.    program or in using of its output. There is no warranty of any kind.
  330.  
  331.    archive contents:
  332.    
  333.    AmiDass05sc      21428 bytes   executable for Amiga
  334.    PcDass05sc.exe   16206 bytes   executable for PC
  335.    readme.doc       13710 bytes   this text
  336.  
  337.  
  338. DONATIONS/GIFTS:
  339.    
  340.    welcome :-) (If you've got a Sky viewing card that you don't need any
  341.    more (e.g. if it is expired [if it says anything else but 'your card
  342.    is invalid'], or you subscribed twice by accident ;-) please don't
  343.    mind to send that one to me...
  344.    
  345.  
  346. AUTHOR:
  347.  
  348.    Klaus Hegemann     klausi@higgens.tng.oche.de
  349.    Hirschgraben 13    hegeman@reze-1.rz.rwth-aachen.de
  350.    52062 Aachen
  351.    -Germany-
  352.